---
title: OpenAPI
description: Generating docs for OpenAPI schema
---

<Callout type="warning" title="Before Reading">

- Only OpenAPI 3.0 and 3.1 are supported.
- It only works under RSC
  environments.

</Callout>

## Manual Setup

Install the required packages.

```npm
npm i fumadocs-openapi shiki
```

<Callout title="For Bun PM" type="warning">
  If you encountered any issues, please check
  [#2223](https://github.com/fuma-nama/fumadocs/issues/2223).
</Callout>

### Generate Styles

Add the following line:

```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import 'fumadocs-openapi/css/preset.css';
```

### Configure Plugin

Create an OpenAPI instance on the server.

```ts tab="lib/openapi.ts"
import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  // the OpenAPI schema, you can also give it an external URL.
  input: ['./unkey.json'],
});
```

```ts tab="lib/source.ts"
import { openapiPlugin } from 'fumadocs-openapi/server';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  // [!code ++] optional: adds a badge to each page item in page tree
  plugins: [openapiPlugin()],
});
```

Create a `APIPage` component:

```tsx tab="components/api-page.tsx"
import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
});
```

```tsx tab="components/api-page.client.tsx"
'use client';
import { defineClientConfig } from 'fumadocs-openapi/ui/client';

export default defineClientConfig({
  // client-side config
});
```

### Generate Pages

<Tabs items={["MDX Files", "Virtual Files"]}>
<Tab>

You can generate MDX files directly from your OpenAPI schema.

Create a script:

```js title="scripts/generate-docs.ts"
import { generateFiles } from 'fumadocs-openapi';
import { openapi } from '@/lib/openapi';

void generateFiles({
  input: openapi,
  output: './content/docs',
  // we recommend to enable it
  // make sure your endpoint description doesn't break MDX syntax.
  includeDescription: true,
});
```

Generate docs with the script:

```bash
bun ./scripts/generate-docs.ts
```

Add the `APIPage` component to your MDX Components.

```tsx title="mdx-components.tsx"
import defaultComponents from 'fumadocs-ui/mdx';
import { APIPage } from '@/components/api-page';
import type { MDXComponents } from 'mdx/types';

// make sure you can use it in MDX files
export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultComponents,
    APIPage,
    ...components,
  };
}
```

</Tab>
<Tab>

You can also use it without generating real files by integrating into [Loader API](/docs/headless/source-api/source).

```ts title="lib/source.ts"
import { loader, multiple } from 'fumadocs-core/source';
import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
import { docs } from 'fumadocs-mdx:collections/server';
import { openapi } from '@/lib/openapi';

export const source = loader(
  // [!code ++:6]
  multiple({
    docs: docs.toFumadocsSource(),
    openapi: await openapiSource(openapi, {
      baseDir: 'openapi',
    }),
  }),
  {
    baseUrl: '/docs',
    plugins: [openapiPlugin()],
    // ...
  },
);
```

It shares a different type from your original source, explicit handling of OpenAPI pages might be necessary (e.g. in your page component).

```tsx title="docs/[[...slug]]/page.tsx"
import { APIPage } from '@/components/api-page';

function Page() {
  const page = source.getPage('...');

  if (page.data.type === 'openapi') {
    return (
      <DocsPage full>
        <h1 className="text-[1.75em] font-semibold">{page.data.title}</h1>

        <DocsBody>
          <APIPage {...page.data.getAPIPageProps()} />
        </DocsBody>
      </DocsPage>
    );
  }

  // your original flow below...
}
```

</Tab>
</Tabs>

## Features

The official OpenAPI integration supports:

- Basic API endpoint information
- Interactive API playground
- Example code to send request (in different programming languages)
- Response samples and TypeScript definitions
- Request parameters and body generated from schemas

### Demo

[View demo](/docs/openapi).
